import Link from 'next/link';

# Getting Started

## Quick Start

```sh
npx create-razzle-app my-app
cd my-app
npm start
```

> If you've previously installed `create-razzle-app` globally via `npm install -g create-razzle-app`, we recommend you uninstall the package using `npm uninstall -g create-razzle-app` or `yarn global remove create-razzle-app` to ensure that `npx` always uses the latest version.

_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))_

Then open http://localhost:3000/ to see your app. Your console should look like this:

<img
  src="https://cloud.githubusercontent.com/assets/4060187/26324663/b31788c4-3f01-11e7-8e6f-ffa48533af54.png"
  width="500px"
  alt="Razzle Development Mode"
/>

**That's it**. You don't need to worry about setting up multiple webpack configs or other build tools. Just start editing `src/App.js` and go!

## Razzle has many examples, we might have one that fits your needs

See: [The examples](https://github.com/jaredpalmer/razzle/tree/master/examples)

## Commands

Below is a list of commands you will probably find useful.

### npm start

Runs the project in development mode.
You can view your application at `http://localhost:3000`

The page will reload if you make edits.

### npm run build

Builds the app for production to the build folder.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

By default this uses NODE_ENV=production and asks if you want to run it.

If you don't want the confirmation add --noninteractive to your build command.

If you want to use a different env file e.g. .env.something-staging file you can add --node-env=something-staging

### npm run start:prod

Runs the compiled app in production.

You can again view your application at `http://localhost:3000`

### npm test

Runs the test watcher (Jest) in an interactive mode.
By default, runs tests related to files changed since the last commit.

### npm export

Exports a static version of the application in production mode. Must add the `export` command to `package.json`'s scripts along with a `static_export.js` file in the `src` directory. See [Static Site Generation](https://razzlejs.org/docs/static-export/) for more details.

### rs

If your application is running, and you need to manually restart your server, you do not need to completely kill and rebundle your application. Instead you can just type `rs` and press enter in terminal.

<img
  src="https://user-images.githubusercontent.com/4060187/37915268-209644d0-30e7-11e8-8ef7-086b529ede8c.png"
  width="500px"
  alt="Razzle Hot Restart"
/>

## Dependencies

To make sure Razzle is installed properly make sure Razzle devDependencies are installed, run:

```bash
yarn add --dev \
  razzle \
  razzle-dev-utils \
  babel-preset-razzle
```

... and Razzle peerDependencies are installed, run:

```bash
yarn add --dev \
  webpack-dev-server@3.11.0 \
  mini-css-extract-plugin@0.9.0 \
  postcss@8.2.4
```

Choose your webpack version

```bash
yarn add --dev webpack@5.65.0 html-webpack-plugin@5.2.0
# or
yarn add --dev webpack@4.46.0 html-webpack-plugin@4.5.2
```

Also if there are issues, try adding specific package versions to resolutions in `package.json`.

## Common issues

If you have issues with css this might be related to postcss being resolved wrong.

To fix this add:

```json
{
  "postcss": "8.2.4"
}
```
To resolutions in your package.json. For npm see [here](https://stackoverflow.com/questions/52416312/npm-equivalent-of-yarn-resolutions).

If you get an error like this:

```
node_modules/react-images-upload/index.css:1
.fileUploader {
^

SyntaxError: Unexpected token '.'
    at wrapSafe (internal/modules/cjs/loader.js:1072:16)
```

It means node tries to use `index.css` as a node module.

To fix this make sure the module with the css is not externalized.

```js
// razzle.config.js
'use strict';

module.exports = {
  modifyWebpackOptions({
    options: {
      webpackOptions, // the modified options that was used to configure webpack/ webpack loaders and plugins
    }
  }) {

      webpackOptions.notNodeExternalResMatch = (request, context) => {
         return /react-images-upload/.test(request)
      };

    return webpackOptions;
  },
};
```

Dev server not starting and no errors show up

Make razzle more verbose:

```js
// razzle.config.js
'use strict';

module.exports = {
  options: {
    verbose: true
  }
};
```

## Debugging with Inspector

- `npm start -- --inspect=[host:port]` or `yarn start --inspect=[host:port]` This will start the node server and enable the inspector agent. The `=[host:port]` is optional and defaults to `=127.0.0.1:9229`. For more information, see [this](https://nodejs.org/en/docs/guides/debugging-getting-started/).

- `npm start -- --inspect-brk=[host:port]` or `yarn start --inspect-brk=[host:port]` This is the same as `--inspect`, but will also break before user code starts. (to give a debugger time to attach before early code runs) For more information, see [this](https://nodejs.org/en/docs/guides/debugging-getting-started/).

- `npm test -- --inspect=[host:port]` or `yarn test --inspect=[host:port]` This will start the tests server and enable the inspector agent. The `=[host:port]` is optional and defaults to `=127.0.0.1:9229`. For more information, see [this](https://nodejs.org/en/docs/guides/debugging-getting-tested/).

- `npm test -- --inspect-brk=[host:port]` or `yarn test --inspect-brk=[host:port]` This is the same as `--inspect`, but will also break before user code starts. (to give a debugger time to attach before early code runs) For more information, see [this](https://nodejs.org/en/docs/guides/debugging-getting-started/).
